1 Introduction
This is a dummy example only for the purpose to use this repo as a template starter for creating new formats.
2 Structure of this repository
Everything for the extensions is in _extensions. See Quarto doc for details.
In
partials, you’ll find the.texpartials that can be used and should be removed or tweaked,sYour extension can make shortcodes and lua filters available. This document shows the effect of the one provided in the
aftformat.aftformat sets some defaults which are different frompdforhtml, link setting links to URL in read inside PDF output.
Source repository for this template format can found on Github
2.1 _extensions\aft
In this folder you’ll find everything that defines the extensions which could be installed using quarto install extension or be part of the template when using quarto use template
- Format Metadata
-
This is in
_extension.ymlis where all the metadata about the format are defined so that Quarto knows what to use. Adapt this file for you own template. - Partials
-
In
partials, there are the.texfiles that will be used as Pandoc’s template. We provide here all the partials supported by Quarto and custom one for this format. Quarto allows to provide partials to ease the process of tweaking the default latex Pandoc’s template and keeping it up to date.
This template repo contains all the relevant partials that you can use with Quarto as example. We only tweakedtitle.texto show the usage of a custom partials called_custom.tex.
Only keep the partials that you need to tweak for the format you are creatingIf you need to completely change the default template (i.g customizing partials is not enough), then you need to provide your own template to Pandoc based on
template.texand also using partials or not. This can be provided using thetemplateYAML key in_extension.ymlfor Quarto to use it.This is considered advanced configuration as it will be harder to maintain than only using partials but could be required for some specific format. Be aware that this may lead to loose some Pandoc or Quarto features tied to default
template.texcontent if you remove some specific parts. - Lua Filters
-
Most of the time, custom formats will need Lua filters to provide specific features like cross format supports or provides custom shortcodes through the Quarto extension mechanism. Those filters will be available to the user and could be used in the custom formats (according to
_extensionsmetadata). We have provided two examples:color-text.lua, a Lua filter used to add color to inline text for PDF and HTML outputs using the same Markdown syntaxshorcodes.lua, a Lua filter which follow Quarto custom shortcodes guidelines to provide a{{< LaTeX >}}shortcode to nicely print LaTeX in PDF and HTML.
Remove or replace with your own Lua filters
- Format resources
-
Resources required by the format needs to be available. We have provided two examples:
te.bstis a biblio style file for demo. It has been downloaded from https://www.economics.utoronto.ca/osborne/latex/TEBST.HTM (http://econtheory.org/technical/te.bst) - Licence LPPLaft.clsis a dummy class file for this example format. It is a copy of officialarticle.cls, the one provided in LaTeX installation (i.e atkpsewhich article.cls) and renamed as example (Licence LaTeX Project Public License)custom.scssis a style file to have a custom theme for our HTML format so that our Lua filter featurecolor-tex.luaworks.
Those files are referenced within the
_extension.ymlto be used with our example format.Remove and replace with your own resources
.quartoignore-
Sometimes it is useful to have some files only needed for reference or for development. They should be available in the source repository but not downloaded to the user when
quarto use templateis used.Use
.quartoignoreto register such file and folder (one file or folder per line) style-guidefolder-
For
quarto-journalsformat, usestyle-guidefolder to include any documentation and resourced used for format creation, like a journal style guide or original.textemplate. This folder is already added in.quartoignorein this example repo.Remove, rename or add to this folder
template.qmd-
This file is the template document that shows how to use the custom format. It will be downloaded with other resource by
quarto use template, and even offered to be renamed if the nametemplate.qmdis used.This file will usually use the custom format (here
aft-pdfandaft-html) and show how to use the template. When you’ll copy this template, you should be able to render this document to the demo format.Adapt this file to provide a suitable template for your custom format
- Other files
-
Other files are needed by the template and are usually user provided - they are not part of the custom format.
Here
bibliography.bibis here to demo the usage of the bst file from the custom format.Remove this file and provide a suitable one for your template
3 Checklist: Creating a custom format
Here is the checklist to help you know what to modify:
- Read the resources mentioned at the top,
- Use this template repo to create a new repository for your format (Click on “Use this template” to create new github repo)
- Once you are acquainted with the content, remove the resources that are there only as example (see above)
- Update README by replacing
aftandArticle Format Templatementions for your journal format - Keep only the template partials that you need to tweak, and add custom ones if needed
- Add any Lua filters for shortcodes and other that would be useful to create the expected output format
- Add any external resource your format will need, and that should be part of the extension format that will be downloaded,
- Check
_extension.ymlis updated correctly - Modify the skeleton
template.qmdto your format and add any required resources to be downloaded to user. - Check
.quartoignoreis updated which everything that should not be downloaded. - Publish a demo of you format to github pages of the repo by using
quarto publishcommand
4 Demo of some features found in this demo journal template
4.1 Shortcode demo
PDF are rendered using \LaTeX but it is best if one can use a Markdown syntax for cross format support.
\LaTeX used in source is a shortcode syntax where the shortcode is included in the extension folder _extensions
4.2 Code chunk
This format hide chunks by default as option has been set in _extension.yml file.
But you can set echo option to true locally in the chunk
Show the code
m_pois <- glm(Days ~ (Eth + Sex + Age + Lrn)^2, data = quine, family = poisson)
summary(m_pois)
Call:
glm(formula = Days ~ (Eth + Sex + Age + Lrn)^2, family = poisson,
data = quine)
Deviance Residuals:
Min 1Q Median 3Q Max
-7.6533 -2.7796 -0.5301 1.5749 8.1955
Coefficients: (1 not defined because of singularities)
Estimate Std. Error z value Pr(>|z|)
(Intercept) 2.93246 0.09826 29.843 < 2e-16 ***
EthN -0.17399 0.12134 -1.434 0.1516
SexM -0.71452 0.12229 -5.843 5.14e-09 ***
AgeF1 -0.04270 0.12691 -0.336 0.7365
AgeF2 -0.08632 0.16164 -0.534 0.5933
AgeF3 -0.15290 0.11898 -1.285 0.1987
LrnSL 0.21608 0.14558 1.484 0.1377
EthN:SexM 0.43902 0.09208 4.768 1.86e-06 ***
EthN:AgeF1 -0.92889 0.14657 -6.337 2.34e-10 ***
EthN:AgeF2 -1.33398 0.13504 -9.879 < 2e-16 ***
EthN:AgeF3 -0.11242 0.13478 -0.834 0.4042
EthN:LrnSL 0.26415 0.11378 2.322 0.0203 *
SexM:AgeF1 -0.05565 0.16303 -0.341 0.7328
SexM:AgeF2 1.09942 0.15281 7.195 6.26e-13 ***
SexM:AgeF3 1.15949 0.13859 8.366 < 2e-16 ***
SexM:LrnSL 0.04143 0.13718 0.302 0.7627
AgeF1:LrnSL -0.13019 0.15688 -0.830 0.4066
AgeF2:LrnSL 0.37340 0.14563 2.564 0.0103 *
AgeF3:LrnSL NA NA NA NA
---
Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
(Dispersion parameter for poisson family taken to be 1)
Null deviance: 2073.5 on 145 degrees of freedom
Residual deviance: 1368.7 on 128 degrees of freedom
AIC: 1993.1
Number of Fisher Scoring iterations: 5
4.3 Text color
Our format makes applying color on inline text possible using the [content]{color=<name>} syntax. Let’s see an example.
Here we are using a special feature of our format which is the coloring because pink is a nice color.
This is possible thanks to the Lua Filter included in the custom extension format.
Using references
I did not read this book (CameronTrivedi2013?) but it must be interesting.
5 Introduction
5.1 About this document
This document provides a template based on the quarto system for contributions to Computo Computo Team (2021). We show how Python (Perez et al. 2011) or R (R Core Team 2020) code can be included.
5.2 Advice for writting your manuscript
First make sure that you are able to build your manuscript as a regular notebook on your system. Then you can start configure the binder environment.
6 Formatting
This section covers basic formatting guidelines. Quarto is a versatile formatting system for authoring HTML based on markdown, integrating \LaTeX and various code block interpreted either via Jupyter or Knitr (and thus deal with Python, R and many other langages). It relies on the Pandoc Markdown markup language.
To render/compile a document, run quarto render. A document will be generated that includes both content as well as the output of any embedded code chunks within the document:
quarto render content.qmd # will render to html6.1 Basic markdown formatting
Bold text or italic
- This is a list
- With more elements
- It isn’t numbered.
But we can also do a numbered list
- This is my first item
- This is my second item
- This is my third item
6.2 Mathematics
6.2.1 Mathematical formulae
LaTeX code is natively supported1, which makes it possible to use mathematical formulae:
will render
f(x_1, \dots, x_n; \mu, \sigma^2) = \frac{1}{\sigma \sqrt{2\pi}} \exp{\left(- \frac{1}{2\sigma^2}\sum_{i=1}^n(x_i - \mu)^2\right)}
It is also posible to cross-reference an equation, see Equation 1:
\begin{aligned} D_{x_N} & = \frac12 \left[\begin{array}{cc} x_L^\top & x_N^\top \end{array}\right] \, \left[\begin{array}{cc} L_L & B \\ B^\top & L_N \end{array}\right] \, \left[\begin{array}{c} x_L \\ x_N \end{array}\right] \\ & = \frac12 (x_L^\top L_L x_L + 2 x_N^\top B^\top x_L + x_N^\top L_N x_N), \end{aligned} \tag{1}
6.2.2 Theorems and other amsthem-like environments
Quarto includes a nice support for theorems, with predefined prefix labels for theorems, lemmas, proposition, etc. see this page. Here is a simple example:
Theorem 1 (Strong law of large numbers) The sample average converges almost surely to the expected value:
\overline{X}_n\ \xrightarrow{\text{a.s.}}\ \mu \qquad\textrm{when}\ n \to \infty.
See Theorem 1.
6.3 Code
Quarto uses either Jupyter or knitr to render code chunks. This can be triggered in the yaml header, e.g., for Jupyter (should be installed on your computer) use
---
title: "My Document"
author "Jane Doe"
jupyter: python3
---For knitr (R + knitr must be installed on your computer)
---
title: "My Document"
author "Jane Doe"
---You can use Jupyter for Python code and more. And R + KnitR for if you want to mix R with Python (via the package reticulate Ushey et al. (2020)).
6.3.1 R
R code (R Core Team 2020) chunks may be embedded as follows:
Show the code
x <- rnorm(10)6.3.2 Python
---
title: "My Document"
author "Jane Doe"
jupyter: python3
---7 Figures
Plots can be generated as follows:
Interactive plots may also be produced in the HTML output of the document:
It is also possible to create figures from static images:

7.1 Tables
Tables (with label: @tbl-mylabel renders Table 1) can be generated with markdown as follows
| Tables | Are | Cool |
|---|---|---|
| col 1 is | left-aligned | $1600 |
| col 2 is | centered | $12 |
| col 3 is | right-aligned | $1 |
Table can also be generated by some code, for instance with knitr here:
| speed | dist | |
|---|---|---|
| Min. : 4.0 | Min. : 2.00 | |
| 1st Qu.:12.0 | 1st Qu.: 26.00 | |
| Median :15.0 | Median : 36.00 | |
| Mean :15.4 | Mean : 42.98 | |
| 3rd Qu.:19.0 | 3rd Qu.: 56.00 | |
| Max. :25.0 | Max. :120.00 |
7.2 Algorithms
A solution to typeset pseudocode just like you would do with \LaTeX, yet with HTML output is to rely on the JavaScript peudocode.js. Your pseudocode is written inside a <pre> tag. You need to modify the file includes/pseudocode-footer.html so that the Id of the rendered element match the one in <pre id ="">. The result is as follows:
\begin{algorithm}
\caption{A simple Algorithm}
\begin{algorithmic}
\STATE \textbf{Data}: $\mathcal{X} = \{x_1, \dots, x_n\}$
\STATE optimization parameters: number of iterations $T$, learning rate $\eta$
\STATE \textbf{Result}: output $\mathcal{Y} = \{y_1, \dots, y_n\}$
\PROCEDURE{myproc}{$T$, $\eta$}
\FOR{$t = 0$ \TO $T$}
\STATE do something (and fast please)
\ENDFOR
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}
7.3 Handling references
7.3.1 Bibliographic references
References are displayed as footnotes using BibTeX, e.g. [@computo] will be displayed as (Computo Team 2021), where computo is the bibtex key for this specific entry. The bibliographic information is automatically retrieved from the .bib file specified in the header of this document (here:references.bib).
7.3.2 Other cross-references
As already (partially) seen, Quarto includes a mecanism similar to the bibliographic references for sections, equations, theorems, figures, lists, etc. Have a look at this page.
Bibliography
& Engineering, AIP Publishing, 13, 13–21.